Overlay deprecation in documentation #7803

ahh-docker · 2018-12-06T17:21:01Z

…eed to start here. Also might need to remove the graphic.

Proposed changes

Unreleased project version (optional)

Related issues (optional)

…eed to start here. Also might need to remove the graphic.

ahh-docker · 2018-12-06T17:21:15Z

@mark-church @andrewhsu PTAL. Thanks! I know I need to get rid of a graphic for overlay, but I want to make sure the rest flows and I didn't remove anything that didn't need to be removed.

mark-church · 2018-12-06T17:22:35Z

Adding in @mataneja in my place to review since he is the PM for engine (and overlay driver)

GordonTheTurtle · 2018-12-06T17:29:44Z

Deploy preview for docsdocker ready!

Built with commit 111ae39

https://deploy-preview-7803--docsdocker.netlify.com

ahh-docker · 2018-12-07T17:36:15Z

Thanks @mark-church! I've added @mataneja to the reviewers!

storage/storagedriver/overlayfs-driver.md

mataneja · 2018-12-11T16:43:33Z

Overall LGTM. @andrewhsu / @thaJeztah please review.

storage/storagedriver/index.md

storage/storagedriver/overlayfs-driver.md

thaJeztah · 2018-12-12T15:16:31Z

storage/storagedriver/overlayfs-driver.md

 > For more information about differences between `overlay` vs `overlay2`, check
 > [Docker storage drivers](select-storage-driver.md).

+The `overlay2` driver only works with two layers. This means that multi-layered


this is about the overlay driver (which only can work with a single "lowerdir". The overlay2 driver does not have this limitation, and doesn't have to do the hardlink trick to workaround the "single lowerdir" limitation

@thaJeztah can you please explain to me what edits need to be done? thanks.

What @thaJeztah means is this paragraph describes the details of overlay and is not applicable to overlay2.

storage/storagedriver/overlayfs-driver.md

thaJeztah · 2018-12-12T15:22:53Z

storage/storagedriver/overlayfs-driver.md

-    less performant than `overlayfs` on initial read, because it must look
-    through more layers, but it caches the results so this is only a small
-    penalty.
+    for files in images with many layers. This advantage applies to the `overlay2` 


This advantage actually was for the overlay driver (as explained in the removed part); overlay2 has a performance penalty on first read (as it has multiple lowerdirs), but once cached, that performance penalty no longer applies.

thaJeztah · 2018-12-12T15:24:54Z

storage/storagedriver/overlayfs-driver.md

@@ -490,14 +442,6 @@ Both `overlay2` and `overlay` drivers are more performant than `aufs` and
  far larger latencies if searching through many AUFS layers. `overlay2` supports
  multiple layers as well, but mitigates any performance hit with caching.

- **Inode limits**. Use of the `overlay` storage driver can cause excessive


Wondering if we should add a page about the overlay driver and capture this information there.

This issue has been the major pain-point for the legacy overlay driver; people ran out of inodes (resulting in "no space on device") whereas actually there was enough space left, only not enough inodes

@thaJeztah Since we're deprecating the overlay driver, why should we keep documentation on the older driver? If you want to have something on why we are deprecating it, I'm for it.

@andrewhsu What are your thoughts?

We should have that info because even if the driver is deprecated, there are still people using it (and will be, for at least a few years). Having a doc to help them out is good, especially since we already have that info written -- it just need to be moved into a separate doc having a preamble/disclaimer like "Note overlay is deprecated and should not be used; the information below is kept here mostly for historical purposes" or so.

thaJeztah · 2018-12-12T15:26:09Z

storage/storagedriver/select-storage-driver.md

@@ -76,7 +76,7 @@ the Docker edition you use.

 In addition, Docker does not recommend any configuration that requires you to
 disable security features of your operating system, such as the need to disable
-`selinux` if you use the `overlay` or `overlay2` driver on CentOS.
+`selinux` if you use the `overlay2` driver on CentOS.


We need to double check selinux; IIRC, SELinux is now supported with overlay/overlay2, but there may be some limitations still

@thaJeztah Can you please let me know what the limitations are?

thaJeztah · 2018-12-12T15:26:41Z

storage/storagedriver/overlayfs-driver.md

@@ -342,23 +298,23 @@ hard links to the data that is shared with lower layers. This allows for
 efficient use of disk space.

 ```bash
-$ ls -i /var/lib/docker/overlay/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls
+$ ls -i /var/lib/docker/overlay2/38f3ed2eac129654acef11c32670b534670c3a06e483fce313d72e3e0a15baa8/root/bin/ls


I'll have to revisit this section (haven't had time yet to check if it's still current)

@thaJeztah please let me know. Thanks.

ahh-docker · 2018-12-18T16:19:11Z

@JustinINevill This is still in technical review.

kolyshkin

Left a few comments; also would be great to squash the commits for the sake of easier review.

kolyshkin · 2019-01-22T23:19:13Z

storage/storagedriver/index.md

+Storage drivers create data in the writable layer of your container.  The files won't 
+be persisted after the container is deleted, and both read and write speeds are low.
+
+Docker recommends Overlay2 for the storage driver.


No need to have it Capitalized, i.e.
Overlay2 -> overlay2

kolyshkin · 2019-01-22T23:24:26Z

storage/storagedriver/overlayfs-driver.md

+
+> **Note**: The `overlay` driver is deprecated in Docker for 18.09 and later.
+> Docker recommends `overlay2` for its storage driver.
+> 


The information about what kernel is required for overlay2 ("you need version 4.0 or higher of the Linux kernel"...) is useful and should not be removed.

kolyshkin · 2019-01-22T23:26:07Z

storage/storagedriver/overlayfs-driver.md

 > For more information about differences between `overlay` vs `overlay2`, check
 > [Docker storage drivers](select-storage-driver.md).

+The `overlay2` driver only works with two layers. This means that multi-layered


What @thaJeztah means is this paragraph describes the details of overlay and is not applicable to overlay2.

storage/storagedriver/overlayfs-driver.md

kolyshkin · 2019-01-22T23:32:22Z

storage/storagedriver/overlayfs-driver.md

@@ -490,14 +442,6 @@ Both `overlay2` and `overlay` drivers are more performant than `aufs` and
  far larger latencies if searching through many AUFS layers. `overlay2` supports
  multiple layers as well, but mitigates any performance hit with caching.

- **Inode limits**. Use of the `overlay` storage driver can cause excessive


We should have that info because even if the driver is deprecated, there are still people using it (and will be, for at least a few years). Having a doc to help them out is good, especially since we already have that info written -- it just need to be moved into a separate doc having a preamble/disclaimer like "Note overlay is deprecated and should not be used; the information below is kept here mostly for historical purposes" or so.

ahh-docker · 2019-02-11T21:19:44Z

@kolyshkin @thaJeztah Can I get together with the two of you and get this fixed and merged? I'd like to get it out of my queue, and it's gotten quite unweidy.. Thanks. :)

traci-morrison · 2019-12-11T20:53:47Z

@thaJeztah Hi Sebastiaan, are the changes in this PR still valid? Thanks!

traci-morrison · 2020-01-13T19:49:01Z

@thaJeztah The Infrastructure team is copying our repos over to Mirantis this week. Any open PRs and issues will be lost, so please do what you can to close or merge this PR before Thursday. Thank you!

usha-mandya · 2020-07-01T11:39:39Z

@thaJeztah Could you let me know whether this PR still valid for Docker docs?

docker-robott · 2022-11-23T15:00:02Z

Thanks for the pull request. We'd like to make our product docs better, but haven’t been able to review all the suggestions.
As our docs have also diverged, we do not have the bandwidth to review and rebase old pull requests.

If the updates are still relevant, review our contribution guidelines and rebase your pull request against the latest version of the docs, then mark it as fresh with a /remove-lifecycle stale comment.
If not, this pull request will be closed in 30 days. This helps our maintainers focus on the active pull requests.

Prevent pull requests from auto-closing with a /lifecycle frozen comment.

/lifecycle stale

Initial overlay deprecation cleanup. There might be more files, but n…

05ee64f

…eed to start here. Also might need to remove the graphic.

ahh-docker self-assigned this Dec 6, 2018

ahh-docker requested review from andrewhsu and mark-church December 6, 2018 17:21

ahh-docker requested a review from mataneja December 7, 2018 17:35

mataneja reviewed Dec 11, 2018

View reviewed changes

storage/storagedriver/overlayfs-driver.md Outdated Show resolved Hide resolved

thaJeztah requested changes Dec 12, 2018

View reviewed changes

ahh-docker added 3 commits December 18, 2018 09:16

Update overlayfs-driver.md

58c2e7f

Update index.md

3509dd9

Update index.md

111ae39

ahh-docker added the process/engineering review needed label Dec 26, 2018

thaJeztah mentioned this pull request Dec 27, 2018

Documentation still explaining devicemapper support although devicemapper support has been removed #7929

Closed

kolyshkin suggested changes Jan 22, 2019

View reviewed changes

bermudezmt assigned shampabh and unassigned ahh-docker Apr 1, 2019

Dawn-Wood removed the OP/pending tech review label Sep 4, 2019

Dawn-Wood unassigned shampabh Sep 4, 2019

traci-morrison self-assigned this Sep 6, 2019

traci-morrison requested review from thaJeztah and removed request for mark-church December 12, 2019 16:00

dockertopia added the area/networking Relates to anything around networking label Jul 8, 2022

docker-robott added the lifecycle/stale label Nov 23, 2022

docker-robott closed this Dec 23, 2022

crazy-max deleted the overlay-deprecation-7439 branch January 14, 2023 13:06

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Overlay deprecation in documentation #7803

Overlay deprecation in documentation #7803

ahh-docker commented Dec 6, 2018

ahh-docker commented Dec 6, 2018 •

edited

Loading

mark-church commented Dec 6, 2018

GordonTheTurtle commented Dec 6, 2018 •

edited

Loading

ahh-docker commented Dec 7, 2018

mataneja commented Dec 11, 2018

thaJeztah Dec 12, 2018

ahh-docker Dec 18, 2018

kolyshkin Jan 22, 2019

thaJeztah Dec 12, 2018

thaJeztah Dec 12, 2018

ahh-docker Dec 18, 2018

kolyshkin Jan 22, 2019

thaJeztah Dec 12, 2018

ahh-docker Dec 18, 2018

thaJeztah Dec 12, 2018

ahh-docker Dec 18, 2018

ahh-docker commented Dec 18, 2018

kolyshkin left a comment

kolyshkin Jan 22, 2019

kolyshkin Jan 22, 2019

kolyshkin Jan 22, 2019

kolyshkin Jan 22, 2019

ahh-docker commented Feb 11, 2019

traci-morrison commented Dec 11, 2019 •

edited

Loading

traci-morrison commented Jan 13, 2020

usha-mandya commented Jul 1, 2020

docker-robott commented Nov 23, 2022

Overlay deprecation in documentation #7803

Overlay deprecation in documentation #7803

Conversation

ahh-docker commented Dec 6, 2018

Proposed changes

Unreleased project version (optional)

Related issues (optional)

ahh-docker commented Dec 6, 2018 • edited Loading

mark-church commented Dec 6, 2018

GordonTheTurtle commented Dec 6, 2018 • edited Loading

ahh-docker commented Dec 7, 2018

mataneja commented Dec 11, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahh-docker commented Dec 18, 2018

kolyshkin left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ahh-docker commented Feb 11, 2019

traci-morrison commented Dec 11, 2019 • edited Loading

traci-morrison commented Jan 13, 2020

usha-mandya commented Jul 1, 2020

docker-robott commented Nov 23, 2022

ahh-docker commented Dec 6, 2018 •

edited

Loading

GordonTheTurtle commented Dec 6, 2018 •

edited

Loading

traci-morrison commented Dec 11, 2019 •

edited

Loading